This section describes the stock methods in the COM wrapper objects created by the Export Bridge Assistant:
Every connector object and custom COM wrapper object has these methods in addition to those defined by the wrapped IDL object.
The Abort method requests that the IDL process containing the underlying IDL object abort its current activity. This method is useful if a given IDL method call is busy for a very long time (e.g., a very long image processing command).
Note: The request is only that, a request, and IDL might take a long time before it actually stops or might completely finish its current activity. Such a wait is an effect of the IDL interpreter.
The client can only abort the current IDL activity if that wrapper object is the current owner of the underlying IDL process.
HRESULT Abort(void)
None
The CreateObject method creates the actual underlying IDL object. The argc, argv, and argpal parameters are used to supply parameters to the underlying IDL object’s Init method. If the Init method does not have any parameters, the caller sets argc, argv, and argpal to 0, NULL, and NULL, respectively.
This method creates IDL objects that use a default licensing algorithm (see IDL Licensing Modes for details). To use a specific IDL licensing mode, use the CreateObjectEx method.
Note: By default, ActiveX controls call the CreateObject method implicitly. In an ActiveX control, calls to the CreateObject method in client code will be ignored if the Explicit CreateObject property in the Export Bridge Assistant project was set to False when the ActiveX control was built.
HRESULT CreateObject ([in] int argc, [in] VARIANT argv, [in] VARIANT argpal)
An integer that specifies the number of elements in the argv and argpal arrays.
A VARIANT containing a COM SafeArray of VARIANT types, one for each parameter to Init. The elements in the array are given in order of the parameters listed in Init, ordered from left to right.
A VARIANT containing a COM SafeArray of 32-bit integer flag values, which can be a combination of the IDLBML_PARMFLAG_CONST and IDLBML_PARMFLAG_CONVMAJORITY values ORed together. The latter value is only used when an argv element is an array itself. For parameters that are not arrays, the argpal[n] value must be 0.
The following constant values defined in the typlib information of a wrapped IDL object can be used:
|
IDLBML_PARMFLAG_CONST |
Use for parameters that are constant (In-Only, meaning that their values cannot be changed). |
|
IDLBML_PARMFLAG_CONVMAJORITY |
Include if the property value is an array. For more information, see Converting Array Majority. |
Note: See COM Object Creation for examples of creating objects from a variety of COM programming languages.
The Init method of the IDL object being wrapped has the following signature:
PRO IDLexFoo::INIT, rect, filename
where rect is an array of 4 integers and filename is a string.
The COM client code that creates an instance of the wrapper object, and calls the CreateObject() method with the rect and filename parameters, would look like the following:
CComSafeArray<int> csa(4);
csa[0] = 0; csa[1] = 0; csa[2] = 5; csa[3] = 10;
CComVariant argv[2];
int argp[2];
argv[0] = csa.Detach();
argp[0] = IDLBML_PARMFLAG_CONST;
argv[1] = "someFilename.txt";
argp[1] = IDLBML_PARMFLAG_CONST;
CComPtr<IMyWrapper> spWrapper;
spWrapper.CoCreateInstance( uuidof(MyWrapper));
spWrapper->CreateObject(2, argv, argp);
The CreateObjectEx method creates the actual underlying IDL object; it differs from the CreateObject method in that it allows the specification of flag values that control the way the IDL process is initialized. The argc, argv, and argpal parameters are used to supply parameters to the underlying IDL object’s Init method. If the Init method does not have any parameters, the caller sets argc, argv, and argpal to 0, NULL, and NULL, respectively. The flags parameter specifies one or more initialization flags governing the way the IDL process is initialized; currently, the available flags control the method used to license the IDL session. (See IDL Licensing Modes for details on the default licensing mechanism.)
Note: By default, ActiveX controls call the CreateObject method implicitly. In an ActiveX control, calls to the CreateObject method in client code will be ignored if the Explicit CreateObject property in the Export Bridge Assistant project was set to False when the ActiveX control was built.
HRESULT CreateObjectEx ([in] int argc, [in] VARIANT argv, [in] VARIANT argpal, [in] long flags))
An integer that specifies the number of elements in the argv and argpal arrays.
A VARIANT containing a COM SafeArray of VARIANT types, one for each parameter to Init. The elements in the array are given in order of the parameters listed in Init, ordered from left to right.
A VARIANT containing a COM SafeArray of 32-bit integer flag values, which can be a combination of the IDLBML_PARMFLAG_CONST and IDLBML_PARMFLAG_CONVMAJORITY values ORed together. The latter value is only used when an argv element is an array itself. For parameters that are not arrays, the argpal[n] value must be 0.
The following constant values defined in the typlib information of a wrapped IDL object can be used:
|
IDLBML_PARMFLAG_CONST |
Use for parameters that are constant (In-Only, meaning that their values cannot be changed). Include if the property value is an array. |
|
IDLBML_PARMFLAG_CONVMAJORITY |
For more information, see Converting Array Majority. |
Flag values that control the way the IDL process is initialized. The following constant values defined in the typlib information of a wrapped IDL object can be used:
|
IDLBML_LIC_FULL |
The application requires that a licensed copy of IDL be installed on the local machine. If IDL is installed but no license is available, the application will run in IDL Demo (7-minute) mode. |
|
IDLBML_LIC_LICENSED_SAV |
The application looks for an embedded license in the save file being restored. |
|
IDLBML_LIC_RUNTIME |
The application looks for a runtime IDL license. If no runtime license is available, the application will run in Virtual Machine mode. |
|
IDLBML_LIC_VM |
The application will run in Virtual Machine mode. |
Note: See COM Object Creation for examples of creating objects from a variety of COM programming languages.
The Init method of the IDL object being wrapped has the following signature:
PRO IDLexFoo::INIT, rect, filename
where rect is an array of 4 integers and filename is a string.
The COM client code that creates an instance of the wrapper object and calls the CreateObjectEx() method with the rect and filename parameters, and which explicitly specifies that it should run in IDL Virtual Machine mode, would look like the following:
CComSafeArray<int> csa(4);
csa[0] = 0;
csa[1] = 0;
csa[2] = 5;
csa[3] = 10;
CComVariant argv[2];
int argp[2];
argv[0] = csa.Detach();
argp[0] = IDLBML_PARMFLAG_CONST;
argv[1] = "someFilename.txt";
argp[1] = IDLBML_PARMFLAG_CONST;
CComPtr<IMyWrapper> spWrapper;
spWrapper.CoCreateInstance( uuidof(MyWrapper));
spWrapper.CreateObjectEx(2, argv, argp, IDLBML_LIC_VM);
The DestroyObject method destroys the underlying IDL object. If the object being destroyed is the last object within an OPS process, the OPS process is also destroyed.
Note: Trying to re-create an object after it has been destroyed is not supported. You must re-define the variable and then re-create the object.
HRESULT DestroyObject(void)
None
The ExecuteString method executes the specified command in the IDL process containing the underlying IDL object.
Note: This method is disabled for applications running in the IDL Virtual Machine.
HRESULT ExecuteString([in] BSTR bstrCmd)
A string containing the IDL command to be executed.
See IDL Command Line with a COM Connector Object for an example that executes any IDL command entered into one textbox and writes IDL output or error information to a second textbox.
The GetIDLObjectClassName method returns the IDL class name of the underlying IDL object.
HRESULT GetIDLObjectClassName([out,retval] BSTR* Name)
A string containing the class name of the IDL object.
When the underlying IDL object was created in the IDL process, it was assigned a variable name. The GetIDLObjectVariableName method returns that name.
HRESULT GetIDLObjectVariableName([out,retval] BSTR* Name)
A string containing the variable name of the IDL object.
The GetIDLVariable method retrieves a named variable from the IDL process containing the underlying IDL object.
Note: This method is disabled for applications running in the IDL Virtual Machine.
HRESULT GetIDLVariable([in] BSTR bstrVar, [out,retval] VARIANT* Value)
A string containing the name of the variable to retrieve from the IDL process.
The variable’s values. If the variable is an array, the array is always converted from IDL majority to the standard COM SAFEARRAY majority ordering.
See Data Manipulation with a COM Connector Object for an array manipulation example that uses the GetIDLVariable, SetIDLVariable and ExecuteString methods.
The GetLastError method gets the error string for the last error that has occurred. It is called after a method call returns an error. The returned error string is usually the actual IDL error message, if IDL generated the error message.
HRESULT GetLastError([out,retval] BSTR* LastError)
The error string for the last error that occurred.
The GetProcessName method returns the name of the process that contains the underlying IDL object.
HRESULT GetProcessName([out,retval] BSTR* Name)
A string containing the name of the process that contains the IDL object.
The SetIDLVariable method sets the specified variable name to the specified value in the IDL process containing the underlying IDL object. If the value is a SAFEARRAY, it is always converted from the standard COM SAFEARRAY majority ordering to IDL majority.
Note: This method is disabled for applications running in the IDL Virtual Machine.
HRESULT SetIDLVariable([in] BSTR bstrVar, [in] VARIANT Value)
A string identifying the variable in the IDL process to be set to Value.
The value for the variable.
See Data Manipulation with a COM Connector Object for an array manipulation example that uses the GetIDLVariable, SetIDLVariable and ExecuteString methods.
The SetProcessName method sets the name of the process that will contain the IDL object. This can only be called before making the CreateObject call. Once the object is created, the process name cannot be reset and calling this method after CreateObject has no effect.
HRESULT SetProcessName([in] BSTR Name)
A string containing the name of the process that will contain the IDL object.